/*!
 * \file UftStraContext.h
 * \project	WonderTrader
 *
 * \author Wesley
 * \date 2020/03/30
 * 
 * \brief UFT策略上下文定义文件
 * 
 * \details 定义了UFT(Ultra Fast Trading)策略上下文类，作为UFT策略和引擎之间的桥梁。
 *          该类继承自UftStraBaseCtx，提供策略执行的环境和回调接口，处理市场数据、
 *          交易事件、订单状态变化等各种实时事件的分发和处理。
 */
#pragma once
#include "UftStraBaseCtx.h"


USING_NS_WTP;

class UftStrategy;

/*!
 * \class UftStraContext
 * \brief UFT策略上下文类
 * 
 * \details UFT策略上下文，继承自UftStraBaseCtx，为UFT策略提供完整的执行环境。
 *          主要功能包括：
 *          - 策略实例的绑定和管理
 *          - 市场数据事件的接收和分发（Tick、订单簿、成交明细等）
 *          - 交易事件的处理（成交、订单状态变化、持仓变化等）
 *          - 交易通道状态管理
 *          - 交易时段生命周期管理
 * 
 * \note 该类是UFT策略与交易引擎的核心接口层
 * \warning 所有回调方法都在高频交易环境下执行，需要保证极低延迟
 */
class UftStraContext : public UftStraBaseCtx
{
public:
	/*!
	 * \brief 构造函数
	 * \param engine UFT引擎指针
	 * \param name 策略上下文名称
	 * 
	 * \details 初始化UFT策略上下文，建立与UFT引擎的关联关系
	 */
	UftStraContext(WtUftEngine* engine, const char* name);
	
	/*!
	 * \brief 析构函数
	 * 
	 * \details 清理策略上下文资源，断开与策略实例的关联
	 */
	virtual ~UftStraContext();

	/*!
	 * \brief 设置策略实例
	 * \param stra UFT策略实例指针
	 * 
	 * \details 绑定策略实例到上下文，建立策略与上下文的双向关联
	 */
	void set_strategy(UftStrategy* stra){ _strategy = stra; }
	
	/*!
	 * \brief 获取策略实例
	 * \return UftStrategy* 策略实例指针
	 * 
	 * \details 获取当前绑定的策略实例
	 */
	UftStrategy* get_stragety() { return _strategy; }

public:
	/*!
	 * \brief 策略初始化回调
	 * 
	 * \details 策略启动时调用，通知绑定的策略实例进行初始化操作，
	 *          如订阅行情、设置初始参数、准备交易环境等
	 */
	virtual void on_init() override;

	/*!
	 * \brief Tick数据回调
	 * \param code 合约代码
	 * \param newTick 新的Tick数据
	 * 
	 * \details 接收实时Tick行情数据，转发给策略实例处理。
	 *          这是UFT策略最重要的数据入口，延迟要求极低
	 */
	virtual void on_tick(const char* code, WTSTickData* newTick) override;

	/*!
	 * \brief 委托队列数据回调  
	 * \param stdCode 标准合约代码
	 * \param newOrdQue 新的委托队列数据
	 * 
	 * \details 接收Level2委托队列数据，提供订单簿深度信息，
	 *          用于高频策略的订单簿分析和流动性评估
	 */
	virtual void on_order_queue(const char* stdCode, WTSOrdQueData* newOrdQue) override;

	/*!
	 * \brief 委托明细数据回调
	 * \param stdCode 标准合约代码
	 * \param newOrdDtl 新的委托明细数据
	 * 
	 * \details 接收Level2委托明细数据，提供单笔委托的详细信息，
	 *          用于分析市场参与者的交易行为和意图
	 */
	virtual void on_order_detail(const char* stdCode, WTSOrdDtlData* newOrdDtl) override;

	/*!
	 * \brief 成交明细数据回调
	 * \param stdCode 标准合约代码
	 * \param newTrans 新的成交明细数据
	 * 
	 * \details 接收Level2成交明细数据，提供逐笔成交信息，
	 *          用于分析市场流动性和价格发现机制
	 */
	virtual void on_transaction(const char* stdCode, WTSTransData* newTrans) override;

	/*!
	 * \brief K线数据回调
	 * \param code 合约代码
	 * \param period K线周期
	 * \param times 周期倍数
	 * \param newBar 新的K线数据
	 * 
	 * \details 接收K线数据更新，用于技术分析和趋势判断。
	 *          虽然UFT主要基于Tick数据，但K线数据可用于宏观趋势判断
	 */
	virtual void on_bar(const char* code, const char* period, uint32_t times, WTSBarStruct* newBar) override;

	/*!
	 * \brief 成交回报回调
	 * \param localid 本地订单ID
	 * \param stdCode 标准合约代码
	 * \param isLong 是否多头方向
	 * \param offset 开平仓标志
	 * \param vol 成交数量
	 * \param price 成交价格
	 * 
	 * \details 接收订单成交通知，更新策略的持仓和风险状态。
	 *          这是交易执行结果的关键反馈
	 */
	virtual void on_trade(uint32_t localid, const char* stdCode, bool isLong, uint32_t offset, double vol, double price) override;

	/*!
	 * \brief 订单状态回调
	 * \param localid 本地订单ID
	 * \param stdCode 标准合约代码
	 * \param isLong 是否多头方向
	 * \param offset 开平仓标志
	 * \param totalQty 订单总量
	 * \param leftQty 剩余数量
	 * \param price 订单价格
	 * \param isCanceled 是否已撤销
	 * 
	 * \details 接收订单状态变化通知，跟踪订单的生命周期，
	 *          包括部分成交、完全成交、撤单等状态变化
	 */
	virtual void on_order(uint32_t localid, const char* stdCode, bool isLong, uint32_t offset, double totalQty, double leftQty, double price, bool isCanceled = false) override;

	/*!
	 * \brief 交易通道就绪回调
	 * 
	 * \details 交易通道连接成功并就绪时触发，表示可以开始进行交易操作。
	 *          策略可以在此时进行交易前的最后准备工作
	 */
	virtual void on_channel_ready() override;

	/*!
	 * \brief 交易通道断开回调
	 * 
	 * \details 交易通道连接断开时触发，策略应停止新的交易操作，
	 *          并采取适当的风险控制措施
	 */
	virtual void on_channel_lost() override;

	/*!
	 * \brief 订单委托结果回调
	 * \param localid 本地订单ID
	 * \param stdCode 标准合约代码
	 * \param bSuccess 委托是否成功
	 * \param message 错误信息（如果失败）
	 * 
	 * \details 接收订单提交结果通知，确认订单是否成功提交到交易所。
	 *          失败时会提供具体的错误信息
	 */
	virtual void on_entrust(uint32_t localid, const char* stdCode, bool bSuccess, const char* message) override;

	/*!
	 * \brief 持仓变化回调
	 * \param stdCode 标准合约代码
	 * \param isLong 是否多头持仓
	 * \param prevol 昨仓数量
	 * \param preavail 昨仓可用数量
	 * \param newvol 今仓数量
	 * \param newavail 今仓可用数量
	 * \param tradingday 交易日
	 * 
	 * \details 接收持仓变化通知，更新策略的持仓状态。
	 *          区分今仓和昨仓，支持精确的仓位管理
	 */
	virtual void on_position(const char* stdCode, bool isLong, double prevol, double preavail, double newvol, double newavail, uint32_t tradingday) override;

	/*!
	 * \brief 交易时段开始回调
	 * \param uTDate 交易日期
	 * 
	 * \details 交易时段开始时触发，策略可以进行交易前的准备工作，
	 *          如重置状态、加载当日参数等
	 */
	virtual void on_session_begin(uint32_t uTDate) override;
	
	/*!
	 * \brief 交易时段结束回调
	 * \param uTDate 交易日期
	 * 
	 * \details 交易时段结束时触发，策略可以进行清理工作，
	 *          如保存状态、计算收益、风险评估等
	 */
	virtual void on_session_end(uint32_t uTDate) override;


private:
	UftStrategy*		_strategy;		///< UFT策略实例指针
};

